dbtのDescriptionにMarkdownで記入する方法を３つ試してみた

さがらです。

早速ですが、dbtのDecriptionといえば、基本的には以下のように直書きで色々書くことが多いと思います。

version: 2

models:
  - name: events
    description: This table contains clickstream events from the marketing website

    columns:
      - name: event_id
        description: This is a unique identifier for the event
        tests:
          - unique
          - not_null

ただ、「Decription内にMarkdownで整理・強調させた表現を入れたい…」というケースはあると思います。

そんなときに使える方法を3つ試してみたので、本記事でまとめてみます。

参考

今回検証する内容ですが、以下の内容を参考にしております。こちらも併せてご覧ください。

方法その１：「>」を使う

まず1つ目は、下記のようにDescriptionに「>」を入れる方法です。強調表現やリンクの設定も可能です。

**ただし、この方法は改行に対応していないため注意が必要です。

version: 2

models:
  - name: customers
    description: >
      これは**強調表現**です。[クラスメソッドのHPへのリンク](https://classmethod.jp/)です。

方法その２：「|」を使う

2つ目の方法ですが、下記のようにDescriptionに「|」を入れる方法です。この方法ならば、改行を入れることも可能なため、見出しや箇条書きにも対応しています。

version: 2

models:
  - name: customers
    description: |
      # 見出し１
      
      - これは**強調表現**です。
      - [クラスメソッドのHPへのリンク](https://classmethod.jp/)です。

      ## 見出し２

      1. 番号１
      2. 番号２

方法その３：docsブロックを使う

３つ目の方法ですが、別途.mdのファイルを定義しておき、その.mdファイルの中で{% docs hogehoge %}ブロック内でMarkdowdnでDescriptionの内容を記述し、yamlファイルからは'{{ doc("hogehoge") }}'で参照するという方法です。

この方法ならば、改行もできる上、複数の同名カラムで使い回すことも可能です。ただ、docsブロックの命名規則や管理方法などには注意が必要となります。

• models/_docs_customers.md

{% docs table_customers %}

# 見出し１
- これは**強調表現**です。
- [クラスメソッドのHPへのリンク](https://classmethod.jp/)です。

## 見出し２
1. 番号１
2. 番号２
      
{% enddocs %}

• models/schema.yml

version: 2

models:
  - name: customers
    description: '{{ doc("table_customers") }}'

おまけ：dbt ExplorerでもMarkdownが反映されているか確認してみた

最後におまけですが、dbt ExplorerでもMarkdownが反映されているか確認してみました。

こちらも、下図のように問題なく確認できました！